🍞 feat: Start Standalone Bun and Hono RAG Service - #330

Summary

Start the new standalone Bun/Hono RAG service, under service/, with an opt-in DOCX POST /v1/extract profile. This replaces the earlier Python implementation on this PR branch. It is not a Hono proxy: extraction runs through the Node AnyDoc native binding in killable Bun child processes.

The base-to-head diff contains no changes to Python application code, its requirements, its existing CI job, database schema, ingestion or /text. The old service remains the compatibility and rollback path. No LibreChat caller is cut over yet, and the new service does not yet implement retrieval, embeddings, reranking or PDF/OCR support. Do not repoint LibreChat's existing RAG_API_URL until its migration and remaining endpoint contracts are implemented.

Mechanism

Bun listener + Hono (port 8001)
  -> strict RAG JWT, document scope
  -> bounded FIFO admission BEFORE body consumption
  -> streamed multipart staging with body/file/part limits
  -> isolated Bun child: validate ZIP -> AnyDoc 0.1.3 -> typed result
  -> bounded IPC -> reaping -> temporary cleanup -> release slot

• Starts without Python, pgvector, embedding credentials or a provider health check. The standalone image contains no Python runtime. The default Python Docker images are not replaced.
• Disabled by default, with no registered extraction route when off.
• Dedicated RAG_JWT_SECRET, expiry/subject/issuer/audience validation and rag:documents; inference-only and legacy session tokens are refused. Startup refuses using the application session key as the service key.
• Existing document-v1 response shape and exact Markdown output are preserved on Marco's DOCX fixture. Parser provenance is pinned to AnyDoc 0.1.3. Package relationships and content types detect embedded artwork/objects even without an image filename extension, and mark the result partial; thumbnail artwork does not. The root OPC relationship resolves the main document, including nonconventional package locations. No hosted OCR or fallback occurs inside the endpoint.
• Limits cover actual streamed HTTP bytes, file bytes, serialized output on both sides, actual inflated ZIP bytes, entry counts, concurrent work and queue length. All extraction operations share an overall deadline. Private random temp directories contain no user-controlled filesystem path.
• Timeout/abort/disconnect kills and reaps the child before cleanup and slot reuse. The listener idle timeout exceeds the bounded application deadline. Early body refusal cancels the upstream producer before releasing its reader lock. Queued cancellation removes waiting work. The child receives no service key or provider credentials and cannot automatically reload dotenv files.
• Separate Bun Dockerfile and CI lane with native contract tests, typecheck, formatting, image build and real HTTP/native smoke in the Python-free image.

Verification

Tests preserve the Python prototype's golden DOCX contract and cover partial media, auth and scope denial, disabled-route behavior, MIME/profile routing, malformed/duplicate multipart, chunked input ceilings, archive size and entry refusals, empty extraction, IPC overproduction, crash/malformed child output, timeout, cancellation/retry, admission-before-body reads, FIFO queued cancellation, and real Bun HTTP disconnects. Only crash/hang/overproduction programs are injected; successful extraction uses the real pinned native binding.

The first independent review returned three P2 findings (non-image artwork filenames, listener idle timeout, relocated main document), all fixed in c967dee985ea26d1de7dd77fcd1b37cbd05f8c4d with regressions. Two additional self-check P2 findings (body producer cancellation and child dotenv loading) are fixed in the same head. No findings were rejected. A fresh independent review of that exact pushed head is running alongside CI. Neither old CI results nor Python prototype tests are presented as covering the new Bun implementation.

Deliberate boundaries

This is the first service slice, not a complete Python replacement. No performance benchmark, browser/LibreChat integration, reranking-quality evaluation, PDF fidelity run or traffic cutover is part of this head. Strict scoped RAG token minting must be wired in the forthcoming LibreChat adapter. completeness is conservative known-omission reporting, not a universal proof of inspectability. Concurrency limits are per process, not billing quotas.

EXTRACTION.md records the independent install/image commands, config, wire contract, error taxonomy, compatibility limits and next slice. Keep raw text, semantic extraction, rich HTML preview and complete content inspection distinct as consumers migrate.

Graph checks used rag_api/lia/document-extraction-contract at 15d84b85443f8cf4e23d083c4af6b135ce3f5344 for removing the old Python additions, supplemented by source/string inspection. The new service/ sources were local-only during those checks. Full graph dependency closure was not computed.